1 Introduction

This training document provides a formal, reproducible framework for acquiring public data programmatically using R.
We focus on four major federal statistical APIs:

  • FRED (Federal Reserve Economic Data)
  • U.S. Census Bureau (Decennial Census & ACS)
  • BEA (Bureau of Economic Analysis)
  • BLS (Bureau of Labor Statistics)

1.1 Using Fredr

fredr provides a complete set of R bindings to the Federal Reserve of Economic Data (FRED) RESTful API, provided by the Federal Reserve Bank of St. Louis. The functions allow the user to search for and fetch time series observations as well as associated metadata within the FRED database. For more details see https://sboysel.github.io/fredr/.

You will need to get your own API key from FRED here https://fred.stlouisfed.org/docs/api/api_key.html.

# Installation
# install.packages("fredr")
# Load the package and then set the key for this session
library(fredr)
fredr_set_key(Sys.getenv("FRED_API_KEY"))
# Your can use `fredr_series_search_text()` to search for a FRED series by text.
fredr_series_search_text("unemployment rate")
# Hint: https://fred.stlouisfed.org/series/UNRATE

# Download one series
unemp <- fredr(series_id = "UNRATE")

# print(unemp)
unemp
# Save
write.csv(unemp, paste0("data/raw/unemp.csv"), row.names = FALSE)

# Customize the date 
unemp_short <- fredr(
  series_id = "UNRATE",
  observation_start = as.Date("2000-01-01"),
  observation_end = as.Date("2025-11-01")
  )

unemp_short

You can set a lot of options for fredr:

# Real Gross Domestic Product, https://fred.stlouisfed.org/series/GDPC1
fredr_series_search_text("GDPC1")  

# Download quarterly (annually) and percent change from 1 year ago
rgdp <- fredr(
  series_id = "GDPC1",
  observation_start = as.Date("2020-01-01"),
  observation_end = as.Date("2024-01-01"),
  frequency = "q", # quarterly
  units = "pc1"    # percent change from 1 year ago
  )

# Save
write.csv(rgdp, paste0("data/raw/rgdp.csv"), row.names = FALSE)
rgdp
# Download multiple series at once, use the `purrr::map_dfr()` function
fredr_series_search_text("FEDFUNDS") # Federal Funds Effective Rate, https://fred.stlouisfed.org/series/FEDFUNDS
df <- purrr::map_dfr(c("UNRATE", "FEDFUNDS"), fredr)
df
# Save
write.csv(df, paste0("data/raw/multiple_series.csv"), row.names = FALSE)

# table(df$series_id)

Once you understand how a function works for one series, you can scale it to many series with a single line of code.

1.1.1 Exercise: Using FRED

Goal: Retrieve another economic indicator from FRED.

  1. Use fredr_series_search_text() to find the series ID for U.S. CPI (inflation). Hint: https://fred.stlouisfed.org/series/CPIAUCSL
  2. Download quarterly CPI data from 2010–2024.

1.2 Using tidycensus

tidycensus is an R package that allows users to interface with a select number of the US Census Bureau’s data APIs and return tidyverse-ready data frames, optionally with simple feature geometry included. tidycensus always works best in a tidy workflow, so using it together with dplyr and ggplot2 is natural.

# Go ahead and install the `tidycensus` package
# install.packages("tidycensus") 
# Load the packages
library(tidycensus)
library(tidyverse)

You will need to have another API key for the census which you can get here: http://api.census.gov/data/key_signup.html. Once activated, use the census_api_key() function to set your key as an environment variable.

census_api_key(Sys.getenv("CENSUS_API_KEY"), install = TRUE, overwrite=TRUE)

Two main functions in tidycensus: - get_decennial(): Obtain data and feature geometry for the decennial US Census 2000, 2010, 2020. https://www.census.gov/data/developers/data-sets/decennial-census.html - get_acs(): Obtain data and feature geometry for the American Community Survey

1.2.1 get_decennial()

# Download 2010 Total Population by state (Decennial Census, variable = P001001)
# Hint: https://api.census.gov/data/2010/dec/sf1/variables.html

pop10 <- get_decennial(
  geography = "state",
  variables = "P001001",
  year = 2010
)

# Save
write.csv(pop10, paste0("data/raw/pop10.csv"), row.names = FALSE)
pop10
# table(pop10$variable)
# Download 2010 Total Population by county in New Jersey (Decennial Census, variable = P001001)
pop10_nj <- get_decennial(
  geography = "county",
  variables = "P001001",
  year = 2010,
  state = "34"
)

pop10_nj
# Save
write.csv(pop10_nj, paste0("data/raw/pop10_nj.csv"), row.names = FALSE)

1.2.2 Exercise: Using get_decennial

Retrieve the 2010 total urban population for your county by census tract.

Hint: Set geography = "tract" and use the variable P002002 (urban population) from https://api.census.gov/data/2010/dec/sf1/variables.html

1.2.3 get_acs()

The American Community Survey (ACS) is an annual survey of approximately 3 million households, and asks more detailed questions than the decennial Census. 5-year ACS data is available from 2009 through 2023; 1-year ACS data is available for geographies of population 65,000 and greater from 2005 through 2023, with the exception of 2020. Defaults to 2023.

# Load ACS 2023 5-year variable names and labels
vars <- load_variables(2023, "acs5", cache = TRUE)
vars
# Retrieve median household income (ACS 5-year, variable B19013_001) by state
# Hint: https://data.census.gov/table/ACSDT5Y2023.B19013

income <- get_acs(
  geography = "state",
  variables = "B19013_001", 
  survey = "acs5",
  year = 2023
)

# Save
write.csv(income, paste0("data/raw/income.csv"), row.names = FALSE)

The output of get_acs() includes the GEOID, NAME, and variable columns along with the ACS estimate and moe, which is the margin of error around that estimate at a 90 percent confidence level

income

One-year ACS data can be requested with the argument survey = "acs1"

income_1yr <- get_acs(
  geography = "state",
  variables = "B19013_001",
  survey = "acs1"
)
# Print
income_1yr
# Save
write.csv(income_1yr, paste0("data/raw/income_1yr.csv"), row.names = FALSE)
# Querying by state
nj_income <- get_acs(
  geography = "county",
  variables = "B19013_001",
  state = "34",
  geometry = FALSE,
  year = 2023,
  survey = "acs5"
)
# Print
nj_income
# Save
write.csv(nj_income, paste0("data/raw/nj_income.csv"), row.names = FALSE)
# Querying by state and county
mercer_income <- get_acs(
  geography = "tract", 
  variables = "B19013_001", 
  state = "NJ", 
  county = "Mercer",
  geometry = FALSE,
  year = 2023,
  survey = "acs5"
)
# Print
mercer_income
# Save
write.csv(mercer_income, paste0("data/raw/mercer_income.csv"), row.names = FALSE)

1.2.4 Exercise: Using get_acs

  1. Use load_variables() to search for the ACS code for educational attainment.
  2. Retrieve the 2023 ACS 5-year estimates for your state, broken down by county, using that variable.

1.3 Using bea.R for BEA data

# Intall and load package
# install.packages("bea.R") 
library(bea.R)

# Set up API key
beaKey <- Sys.getenv("BEA_API_KEY")

# Use `beaSearch` to Search for BEA data by keyword
beaSearch('gross domestic', beaKey, asHtml = TRUE)

You can check the dataset name and table name from here

# Example: Get real GDP percent change
rgdp_us_pc <- beaGet(beaSpecs <- list(
    'UserID' = beaKey ,    
      'Method' = 'GetData',    
      'datasetname' = 'NIPA',    
      'TableName' = 'T10101',     
      'Frequency' = 'Q',    
      'Year' = '2022, 2023, 2024, 2025',    
      'ResultFormat' = 'json'  ), 
  asWide = FALSE)
# Print
rgdp_us_pc
# Save
write.csv(rgdp_us_pc, paste0("data/raw/rgdp_us_pc.csv"), row.names = FALSE)

1.4 Using blsAPI for BLS data

# Load package
library(blsAPI)

# Set up API key
bls_key <- Sys.getenv("BLS_API_KEY")

# Example: Get unemployment rate data for New Jersey (state code 34)
unemp_nj <- blsAPI(
  list(
    'seriesid'='LASST340000000000003',
    'startyear'=2010,
    'endyear'=2025,
    'annualaverage'=TRUE,
    'calculations'=FALSE,
    'registrationKey'=bls_key), 
  api_version = 2, 
  TRUE) 
# Print
unemp_nj
# Save
write.csv(unemp_nj, paste0("data/raw/unemp_nj.csv"), row.names = FALSE)

1.4.1 Exercise: Using blsAPI

Goal: Retrieve labor market indicators.

  1. Download both the NJ total nonfarm employment (SMS34000000000000001).
  2. Download both the statewide unemployment rate and total nonfarm employment series for your chosen state using the appropriate BLS seriesid codes.

2 Summary

This R Markdown document demonstrates:

  • Secure handling of API keys using environment variables
  • Retrieval of official economic, demographic, and labor market data
  • Consistent tidy data workflow across FRED, Census, BEA, and BLS
  • Query patterns for state, county, tract, and national geographies

These tools support evidence-based analysis for workforce development, policy evaluation, and regional economic insights.